// Copyright 2017 The PDFium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com
当然，以下是`CPDF_ToUnicodeMap`类中各个函数的功能概述：

### 公有成员函数(Public Member Functions)

1. * *`explicit CPDF_ToUnicodeMap(RetainPtr<const CPDF_Stream> pStream);`* *
-构造函数：使用给定的`CPDF_Stream`对象初始化`CPDF_ToUnicodeMap`实例。这个流通常包含了ToUnicode CMap数据。

2. * *`~CPDF_ToUnicodeMap();`* *
-析构函数：清理`CPDF_ToUnicodeMap`实例所占用的资源。

3. * *`WideString Lookup(uint32_t charcode) const;`* *
-根据提供的字符码（charcode）查找对应的Unicode值，并返回一个`WideString`类型的字符串表示。

4. * *`uint32_t ReverseLookup(wchar_t unicode) const;`* *
-根据提供的Unicode字符查找对应的字符码（charcode），并返回该字符码。

5. * *`size_t GetUnicodeCountByCharcodeForTesting(uint32_t charcode) const;`* *
-用于测试目的，根据提供的字符码（charcode）获取与之关联的Unicode数量。

### 私有成员函数(Private Member Functions)

1. * *`static std::optional<uint32_t> StringToCode(ByteStringView input);`* *
-将字节字符串转换为字符码（code）。如果转换失败，则返回`std::nullopt`。

2. * *`static WideString StringToWideString(ByteStringView str);`* *
-将字节字符串转换为宽字符字符串（`WideString`）。

3. * *`void Load(RetainPtr<const CPDF_Stream> pStream);`* *
-加载由`pStream`指定的ToUnicode CMap数据到当前映射中。

4. * *`ByteStringView HandleBeginBFChar(CPDF_SimpleParser & parser, ByteStringView previous_word);`* *
-处理CMap文件中的`/beginbfchar`指令，解析单个字符映射条目。`previous_word`是解析器最近返回的单词，函数返回解析器遇到的最后一个单词。

5. * *`ByteStringView HandleBeginBFRange(CPDF_SimpleParser & parser, ByteStringView previous_word);`* *
-处理CMap文件中的`/beginbfrange`指令，解析字符范围映射条目。`previous_word`是解析器最近返回的单词，函数返回解析器遇到的最后一个单词。

6. * *`uint32_t GetMultiCharIndexIndicator() const;`* *
-获取多字符索引指示符，这可能是用于处理复合字符或字符序列的内部方法。

7. * *`void SetCode(uint32_t srccode, WideString destcode);`* *
-设置从源字符码（srccode）到目标Unicode字符串（destcode）的映射关系。

8. * *`void InsertIntoMultimap(uint32_t code, uint32_t destcode);`* *
-向`m_Multimap`成员变量插入一个新的映射条目，确保不会重复插入相同的条目。

这些函数共同工作，以实现对PDF文档中字符编码到Unicode的高效映射和反向映射。
#ifndef CORE_FPDFAPI_FONT_CPDF_TOUNICODEMAP_H_
#define CORE_FPDFAPI_FONT_CPDF_TOUNICODEMAP_H_

#include <map>
#include <optional>
#include <set>
#include <vector>

#include "core/fxcrt/fx_string.h"
#include "core/fxcrt/retain_ptr.h"
#include "core/fxcrt/unowned_ptr.h"

class CPDF_CID2UnicodeMap;
class CPDF_SimpleParser;
class CPDF_Stream;

class CPDF_ToUnicodeMap {
 public:
  explicit CPDF_ToUnicodeMap(RetainPtr<const CPDF_Stream> pStream);
  ~CPDF_ToUnicodeMap();

  WideString Lookup(uint32_t charcode) const;
  uint32_t ReverseLookup(wchar_t unicode) const;

  size_t GetUnicodeCountByCharcodeForTesting(uint32_t charcode) const;

 private:
  friend class CPDFToUnicodeMapTest_StringToCode_Test;
  friend class CPDFToUnicodeMapTest_StringToWideString_Test;

  static std::optional<uint32_t> StringToCode(ByteStringView input);
  static WideString StringToWideString(ByteStringView str);

  void Load(RetainPtr<const CPDF_Stream> pStream);

  // `previous_word` is the most recent word that `parser` returned.
  // Returns the last word `parser` encountered.
  ByteStringView HandleBeginBFChar(CPDF_SimpleParser& parser,
                                   ByteStringView previous_word);
  ByteStringView HandleBeginBFRange(CPDF_SimpleParser& parser,
                                    ByteStringView previous_word);

  uint32_t GetMultiCharIndexIndicator() const;
  void SetCode(uint32_t srccode, WideString destcode);

  // Inserts a new entry which hasn't not been inserted into `m_Multimap`
  // before.
  void InsertIntoMultimap(uint32_t code, uint32_t destcode);

  std::map<uint32_t, std::set<uint32_t>> m_Multimap;
  UnownedPtr<const CPDF_CID2UnicodeMap> m_pBaseMap;
  std::vector<WideString> m_MultiCharVec;
};

#endif  // CORE_FPDFAPI_FONT_CPDF_TOUNICODEMAP_H_
